WeakClone

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods / ODDraft

WeakClone
The WeakClone method ensures that, if the specified object is cloned, weak persistent references to it are maintained.
ODID WeakClone (in ODDraftKey key,
                in ODID objectID, 
                in ODID toObjectID, 
                in ODID scope);
key
The draft key of the current cloning transaction.
objectID
The ID of the persistent object or storage unit to be weakly cloned.
toObjectID
The ID of the destination persistent object or storage unit, or kODNULLID to create a new storage unit in this draft.
scope
The ID of the frame that defines the scope of this cloning operation.
return value
The ID of the duplicated persistent object or storage unit.

DISCUSSION
This method is called by the CloneInto method of persistent objects. You can call this method from your part's CloneInto method if your part has weak persistent references to other objects.
The key parameter is the draft key of the current cloning transaction, which was returned by a call to this draft object's BeginClone method and passed to the calling object's CloneInto method.
The objectID parameter is the ID of an object to be weakly cloned because the calling object has a weak persistent reference to it. The WeakClone method does not guarantee that the specified object will be copied, but if the object is copied because of an existing strong persistent reference to it, the calling object's weak persistent references will be maintained across the cloning transaction.
The toObjectID parameter specifies the ID of the destination storage unit. If the toObjectID parameter is null, a new destination storage unit is created in this destination draft, if necessary.
If the object being weakly cloned has persistent references to other objects, the scope parameter determines which of the referenced objects are within the scope of this cloning operation. Usually the scope parameter is the ID of a frame, and only those objects embedded in that frame are within scope. In the rare case in which the scope parameter is kODIDAll, all referenced objects are within scope.
You must not use the returned ID until the end of the current cloning transaction. Furthermore, before you try to access the persistent object or storage unit with the corresponding ID, you must call the IsValidID method to verify that the ID is still valid.

EXCEPTIONS

kODErrInvalidID
The toObjectID parameter did not specify a valid destination object or storage unit.

SEE ALSO
The ODDraftKey type (page 902).
The ODID type (page 899).
The ODDraft::AbortClone method (page 151).
The ODDraft::BeginClone method (page 159).
The ODDraft::Clone method (page 162).
The ODDraft::EndClone method (page 171).
The ODDraft::IsValidID method (page 175).
The ODPersistentObject::CloneInto method (page 557).
The ODStorageUnit::CloneInto method (page 673).
Listing 2-43 on page 103 in OpenDoc Cookbook.
Listing 2-47 on page 110 in OpenDoc Cookbook.
"Clone" on page 323 in OpenDoc Programmer's Guide.
"The CloneInto Method of Your Part Editor" on page 327 in OpenDoc Programmer's Guide.